Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

Use Meaningful Names

As mentioned in the previous section on Hungarian notation, meaningful variable names are more important than scope and data type prefixes. Make names descriptive enough that another programmer will have no trouble figuring out your variable’s purpose.

Do not use obscure abbreviations. Do not abbreviate to save one or two characters. Instead of writing SpecTeamLdr, use SpecialTeamLeader. Even simple abbreviations take longer to understand than completely spelled phrases. The extra typing you save by abbreviating is not worth the added distraction you impose on the reader.

Some abbreviation is fine, but you should agree with the other team members on the abbreviations you will use. The code will be harder to read if different developers use different strategies. For example, you might agree that count variables should begin with Num as in NumEmployees. The code will be harder to read if it contains the variables NumEmployees, NoCustomers, ProductCount, and so forth.

Capitalize Consistently

The point of Hungarian notation is to make it easier to understand a variable’s scope and data type. Another way to make scope clear is to use consistent capitalization. For example, you can write the names of global variables in MixedCase. Table 3.4 shows one possible capitalization scheme. Notice that this scheme does not differentiate between global and nonglobal constants.

This method indicates scope but not data type. You can add a Hungarian data type prefix, or make variable names descriptive enough that the data types are obvious.

This method also does not handle name conflicts. You cannot declare a module-global variable named Count and a subroutine variable named count. If you try, Visual Basic will change the capitalization of whichever variable you declare first so it matches the second variable’s capitalization.

Avoid Name Conflicts

Visual Basic allows a program to have more than one variable with the same name at different levels of scope. For example, the following code uses variables named A declared with module-global and subroutine-local scope. If you execute this code, it will display the values 1, 2, 3, 1.

Private A As Integer            ‘ Module global scope.

Private Sub Print_Values
    A = 1
    Debug.Print A               ‘ Print the module global value.
    Print_2
    Print_3

    Debug.Print A               ‘ Print the module global value.
End Sub

Private Sub Print_2
Static A As Integer             ‘ Subroutine scope. Starts 0.

    A = 2
    Debug.Print A               ‘ Print the local value.
End Sub

Private Sub Print_3
Dim A As Integer                ‘ Subroutine scope. Starts 0.

    A = 3
    Debug.Print A               ‘ Print the local value.
End Sub

Multiple variables with the same names at different levels of scope can be confusing. Give these variables different names.

As mentioned in the section describing Hungarian notation, variables with different scopes always have different names if you give them scope prefixes. However, even if you use scope qualifiers, variables with similar names can cause a lot of confusion. If you are editing a program, it could be very difficult to decide whether the value you need to modify is mintFiles or intFiles. Even if you know which variable you need, you could easily mistake one for the other when reading the code quickly.

Avoid these difficulties entirely by giving different variables completely different names. In this case it would be better to name the variables NumOpenFiles and num_working_files.

Limit Scope

Give constants, variables, subroutines, functions, and other scoped items the most limited scope possible. Do not use a global variable if a module-global variable will work. Do not use a module-global variable when a subroutine variable will do.

Giving a variable greater scope than necessary increases the chances that some routine will modify the value incorrectly. It allows two routines to use the variable in ways that make them interfere with each other.

Limiting the scope of objects as much as possible hides them from other parts of the code. That means when you read those pieces of code, you do not need to be aware of the objects’ existence. This reduces the number of things you need to think about while you read the code so it makes the code easier to understand.

Use Static Variables

If a subroutine needs to save a value between invocations, use a static variable, not a module global variable. For example, the following code uses a module-global variable to increment a value each time it executes the ShowCount subroutine.

Private the_count As Integer   ‘ Module-global variable.

Private Sub ShowCount()
    the_count = the_count + 1
    MsgBox “Count:” & Str$(the_count)
End Sub

This version uses a static variable instead of a module-global variable.

Private Sub ShowCount()
Static the_count As Integer    ‘ Static variable in the subroutine.

    the_count = the_count + 1
    MsgBox “Count:” & Str$(the_count)
End Sub

If you need to initialize a static variable to some value other than the default defined by Visual Basic, use another static variable named done_before to determine whether the variable has been initialized yet like this:

Private Sub ShowCount()
Static done_before As Boolean    ‘ Have we initialized the count?
Static the_count As Integer      ‘ The count variable.

    ‘ See if the count variable has been initialized yet.
    If Not done_before Then
        ‘ If has not. Initialize it now.
        the_count = 5            ‘ Start with a count of 5.
        done_before = True       ‘ Don’t initialize next time.
    End If

    the_count = the_count + 1
    MsgBox “Count:” & Str$(the_count)
End Sub